%File: ~/OOP/system_of_eqn/linearSOE/SparseGenCol/SuperLU.tex
%What: "@(#) SuperLU.tex, revA"

\noindent {\bf Files}   \\
\indent \#include $<\tilde{
}$/system\_of\_eqn/linearSOE/fullGEN/SuperLU.h$>$  \\ 

\noindent {\bf Class Declaration}  \\
\indent class SuperLU: public SparseGenColLinSolver  \\

\noindent {\bf Class Hierarchy} \\
\indent  MovableObject \\
\indent\indent  Solver \\
\indent\indent\indent LinearSOESolver \\
\indent\indent\indent\indent  SparseGenColLinSolver \\
\indent\indent\indent\indent\indent {\bf SuperLU} \\

\noindent {\bf Description}  \\
\indent A SuperLU object can be constructed to solve
a SparseGenColLinSOE object. It obtains the solution by making calls on the
the SuperLU library developed at UC Berkeley by Prof. James Demmel, 
Xiaoye S. Li and John R. Gilbert.
The SuperLU library contains a set of subroutines to solve a sparse
linear system  $AX=B$. It uses Gaussian elimination with partial
pivoting (GEPP). The columns of A may be preordered before
factorization; the preordering for sparsity is completely separate
from the factorization and a number of ordering schemes are provided. \\

\noindent {\bf Interface}  \\
\indent // Constructor \\
\indent {\em SuperLU();}  \\ \\
\indent // Destructor \\
\indent {\em $\tilde{ }$SuperLU();}\\  \\
\indent // Public Methods \\
\indent {\em int solve(void);} \\
\indent {\em int setSize(void);} \\
\indent {\em int sendSelf(int commitTag, Channel \&theChannel);}\\ 
\indent {\em int recvSelf(int commitTag, Channel \&theChannel,
FEM\_ObjectBroker \&theBroker);}\\ 

\noindent {\bf Constructor}  \\
\indent {\em SuperLU(int permSpec =0, double thresh = 0.0, int panelSize =6,
int relax = 6);}  \\
A unique class tag (defined in $<$classTags.h$>$) is passed to the
SparseGenColLinSolver constructor. Saves the values for the arguments
{\em permSpec}, {\em panelSize}, {\em relax} and {\em thresh} that
will be used when calling the SuperLU routines in {\em solve()} and
{\em setSize()}.

{\em permSpec} defines the ordering routine used in defining the
column permutations {\em permC}: $0$ uses the original ordering
supplied, $1$ defines a min-degree ordering based on $A^TA$ and $2$ a
min-degree ordering based on $A^T + A$. {\em relax} defines the min
number of columns in a subtree for the subtree to be considered a
single supernode. {\em thresh} defines the pivoting threshold: at
step j of the Gaussian elimination if (abs$(A_{jj}) \ge$ {\em thresh}
(max$ i \ge j$ abs($A_{ij}$)). A value for {\em thresh} of $0.0$
definines no pivoting, a value of $1.0$ classical partial pivoting.
{\em panelSize} defines the number of consecutive columns used as a
panel in the elimination. For more information on these values see the
SuperLU manual. \\


\noindent {\bf Destructor} \\
\indent {\em  $\tilde{ }$SuperLU();}\\ 
Invokes delete on {\em permR}, {\em permC} and {\em etree} arrays. \\


\noindent {\bf Public Methods }  \\
\indent {\em int solve(void);} \\
First copies $B$ into $X$ and then solves the FullGenLinSOE system 
it is associated with (pointer kept by parent class) by calling the SeuperLU
routine {\em dgstrf()}, if the system is marked as not having been factored,
or {\em dgstrs()}, if system is marked as having been factored. If the
solution is successfully obtained, i.e. the SuperLU routines return $0$
in the INFO argument, it marks the system has having been
factored and returns $0$, otherwise it prints a warning message and
returns INFO. The solve process changes $A$ and $X$ and sets the char
{\em rafact} to {\em Y}. \\   

\indent {\em int setSize(void);} \\
Obtains the size of the system from it's associaed SparseGenColLinSOE
object. With this information it creates space for the integer arrays
{\em permR}, {\em permC} and {\em etree}. It then creates the
a SuperMatrix for A by calling the SuperLU routine {\em
dCreate\_CompCol\_Matrix()}, sets the column permutation {\em permR}
by calling the SuperLU routine {\em get\_perm\_c(permSpec, A, permC)},
applies this permutation and determines the elimination tree {\em
etree} by calling the SuperLU routine {\em sp\_preorder()}. It then
creates a SuperMatrix for X by calling the SuperLU routine 
{\em dCreate\_Dense\_Matrix()}.
Returns $0$ if successful, prints a warning message and returns
a $-1$ if not enough memory is available for the arrays. \\


\indent {\em  int sendSelf(int commitTag, Channel \&theChannel);} \\ 
Does nothing but return $0$. \\

\indent {\em  int recvSelf(int commitTag, Channel \&theChannel, FEM\_ObjectBroker
\&theBroker);} \\ 
Does nothing but return $0$. \\








